home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 16 / AMIGAplus Sonderheft 16 (1998)(ICP)(DE)[!].iso / pd / anwendungen / xpk_develop / autodocs / xpkpreferences.doc < prev    next >
Text File  |  1998-08-27  |  8KB  |  165 lines
  1. TABLE OF CONTENTS
  2.  
  3. xpkmaster.library/--general--
  4. xpkmaster.library/--replacements--
  5. xpkmaster.library/--semaphore--
  6.  
  7. xpkmaster.library/--general--                   xpkmaster.library/--general--
  8.  
  9.     THE PREFERENCES IDEA
  10.         In version 4 of xpkmaster.library a preferences system has been
  11.         added to support file type depending packing. The implementation in
  12.         master library is done by a semaphore mechanism (see below for this).
  13.         Some additional tools are provided to handle the preferences.
  14.         - XpkMaster      - a normal SYS:Prefs/ preferences program.
  15.         - XpkMasterPrefs - an IPrefs like support for the preferences.
  16.  
  17.     WHEN PREFERENCES ARE USED
  18.     The preferences are used, when no (XPK_Preferences, FALSE) is
  19.     passed. One of the Semaphore installing programs has to be
  20.     started before, as xpkmaster.library only calls the semaphore and
  21.     no files.
  22.     The preferences pack happens when you call XpkPack and the
  23.     XPK_PackMethod tag data contains packmethod "USER".
  24.  
  25.     THE PREFERENCES FORMAT
  26.         The preferences are normal IFF PREF files, with a PRHD chunk
  27.         containing information like the file version and XPKT and XPKM
  28.         chunks with settings relevant to xpk. The structure of these hunks
  29.         are defined in <xpk/xpkprefs.h> as struct XpkMainPrefs and struct
  30.         XpkTypePrefs. These seem to be the first chunks containing
  31.         pointers, therefore I will describe the format below.
  32.  
  33.     IFF POINTERS
  34.         In memory a pointer is a 32 bit variable holding the address of
  35.         another variable it refers to. A pointer of value 0 points to the
  36.         start of memory. The same system is used for pointers in xpk prefs
  37.         files. In the prefs files, ANY pointer refers relative to the first
  38.         byte after the size information of the current chunk. So saving of
  39.         a chunk goes following steps:
  40.         - allocate a area of memory to hold all data
  41.         - copy the main structure (either XpkTypePrefs or XpkMainPrefs) to
  42.           the start of this area
  43.         - copy all other data behind the main structure and set all
  44.           pointers to point to the new place in this area.
  45.         - now subtract the start address of the memory from all pointers
  46.         The last two steps can be done in one.
  47.         For examples how to do this, see the sources in Prefs directory of
  48.         xpk_Source.lha archive.
  49.         Loading needs following steps:
  50.         - load the file into a buffer of chunk size
  51.         - add address of memory area to all pointer values
  52.         - repeat this for all sub structures, you created the real address
  53.           a step before. (In XpkTypePrefs prefs are pointers to XpkTypeData
  54.           which point to strings --> 3 different levels to correct, each
  55.           after each other.)
  56.  
  57. xpkmaster.library/--replacements--         xpkmaster.library/--replacements--
  58.  
  59.     MAKING YOUR OWN PREFERENCES
  60.         The preferences structure of xpkmaster.library is very open. Only a
  61.         few fields of the semaphore (see below) are accessed by the master
  62.         library directly. The preference files will never be accessed by
  63.         the master library. So it is possible to replace the preferences
  64.         system completely with an totally different one (may be depending
  65.         on one of the file identifying libraries). You only have to make
  66.         a program to build a public semaphore with exact the same name as
  67.         the standard one and the same semaphore structure and set
  68.         following fields:
  69.     sem->xps_Version
  70.       Set to version of your structure (for future enhancements).
  71.     sem->xps_PrefsType
  72.       Any ULONG value defining your preferences type. Try to use a
  73.       value not used by another system.
  74.     sem->ps_PrefsData
  75.       Here you may store a pointer to private data. This data is not
  76.       read by xpkmaster.library.
  77.     sem->xps_MainPrefs
  78.       Pointer to default preferences. When this is set to zero,
  79.       internally defaults are used.
  80.     sem->xps_RecogSize
  81.       Size of the file buffer you need for finding the right packer.
  82.     sem->xps_RecogFunc
  83.       Pointer to the function scanning for the right packer. See below
  84.       for more information.
  85.     sem->xps_ProgressFunc
  86.       This is a normal progress hook function, which is called, when
  87.       the user selects XPK_ChunkReport. This function is not required.
  88.     sem->xps_MasterTask
  89.       This a pointer the the task structure of the semaphore installer.
  90.       The installer task has to quit, when it gets a SIGBREAKF_CTRL_C
  91.       signal!
  92.  
  93. xpkmaster.library/--semaphore--               xpkmaster.library/--semaphore--
  94.  
  95.     SEMAPHORE GENERAL
  96.         Semaphores are a way to allow multitasking friendly access to
  97.         public data structures. You get access following way:
  98.  
  99.   Forbid();
  100.   if((sem = (struct XpkPrefsSemaphore *) FindSemaphore(XPKPREFSSEMNAME)))
  101.     ObtainSemaphoreShared((struct SignalSemaphore *) sem);
  102.   Permit();
  103.  
  104.         Now you either own it, or it does not exist. Do not forget to check
  105.         if sem is zero after this piece of code. If not, you can READ all
  106.         documented fields of the semaphore now. (If you want to write, use
  107.         ObtainSemaphore() instead). There are some other methods for access.
  108.         See programming manuals for these.
  109.         
  110.         After work you have to free the semaphore by calling
  111.  
  112.   ReleaseSemaphore((struct SignalSemaphore *) sem);
  113.  
  114.     THE XPKMASTER PREFERENCES SEMAPHORE
  115.         The structure of this semaphore is described in xpk/xpkprefs.h. Most
  116.         of the fields are not accessed by xpkmaster.library. This semaphore
  117.         is public, so you may read all data of it, but because the stuff is
  118.         done by xpkmaster.library there should be no need to do so. Writing
  119.         to the semaphore is allowed too, but should never happen.
  120.         See xpk/xpkprefs.h to get conditions.
  121.  
  122.         The most important part of the semaphore are the fields
  123.         xps_RecogSize and xps_RecogFunc. xps_RecogSize is the size of the
  124.         buffer needed by xps_RecogFunc to find out the filetype.
  125.         xps_RecogFunc is a function to find out the filetype of a file and
  126.         to return the specific packer type for this file.
  127.  
  128.     THE RECOG FUNCTION
  129.         INPUTS
  130.         - A pointer to a buffer holding the beginning of the file is passed
  131.           in register A0.
  132.         - In register A1 the filename of the file is passed. This may be
  133.           zero, because in some cases xpkmaster.library does not have the
  134.           filename.
  135.     - In register A2 a tag list is passed with additionally information,
  136.       f.e. XPK_PackMode for defining better user select abilities and
  137.       XPK_FileName wich may be used for displaying the name in own
  138.       requesters or in chunkhooks. When you do packing in the Recog
  139.       function then pass XPK_FileName as data.
  140.         - In register D0 the size of buffer in A0 is passed. This should
  141.           equal xps_RecogSize or when the file is shorter be the file
  142.           length.
  143.     - In register D1 the complete file size is passed.
  144.         OUTPUT
  145.         - Register D0 passes a pointer to a struct XpkTypeData holding the
  146.           needed information for packing. If no information, return should
  147.           be zero.
  148.         - If return value equals -1 (0xFFFFFFFF), the function will be
  149.           called again with buffer size equal to file size. Do not return -1
  150.           when buffer size already equals file size.
  151.         - When 0 is returned the data from xps_MainPrefs or the internal
  152.           defaults are used.
  153.         NOTE
  154.         - The Recog function should take the filename only as additional
  155.           feature. If no filename is given the filename check cannot take
  156.           place (it is always true).
  157.         - For callers: The returned data is valid only as long as you
  158.           obtain the semaphore.
  159.         - When xpkmaster.library should free the XpkTypeData stuff, then
  160.           set the fields xtd_Memory and xtd_MemorySize. xpkmaster.library
  161.           calls then FreeMem(t->xtd_Memory, t->xtd_MemorySize);. The memory
  162.           must not point to the XpkTypeData structure!
  163.       This is useful, when the type is not in a list, but is created.
  164.       NOTE: The memory area may hold passwords or other data.
  165.